feat: add AGENT-003 Market Monitor and AGENT-004 Validator Monitor character definitions#64
Conversation
…aracter definitions Add the two missing agent character definitions to complete the four-agent roster specified in phase-2/2.4-agent-orchestration.md: - AGENT-003 (Market Monitor): Layer 1 automated agent for credit price monitoring, liquidity tracking, retirement pattern analysis, and fee revenue reporting. Covers workflows WF-MM-01 through WF-MM-03. - AGENT-004 (Validator Monitor): Layer 1 automated agent for validator performance scoring (M014), delegation flow analysis, governance participation tracking, and PoA transition readiness assessment. Covers workflows WF-VM-01 through WF-VM-03. Also updates agents/packages/agents/src/index.ts to register both new characters in the CHARACTERS map, and adds start:market and start:validator scripts to agents/package.json. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Summary of ChangesHello, I'm Gemini Code Assist1! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed! This pull request completes the four-agent roster by integrating two new fully automated Layer 1 agents into the system. The Market Monitor enhances the platform's ability to track and report on ecological credit market dynamics, while the Validator Monitor provides crucial insights into network health and decentralization. These additions expand the system's monitoring capabilities, ensuring comprehensive oversight of both market and infrastructure performance, adhering to the established ElizaOS Character interface pattern. Highlights
Using Gemini Code AssistThe full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips. Invoking Gemini You can request assistance from Gemini at any point by creating a comment using either
Customization To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a Limitations & Feedback Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for GitHub and other Google products, sign up here. Footnotes
|
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Code Review
This pull request introduces two new ElizaOS agents, the Market Monitor and the Validator Monitor, along with their respective configurations and integration into the agent system. The Market Monitor is designed to track ecological credit prices, marketplace liquidity, and retirement activity, while the Validator Monitor focuses on validator performance, uptime, and governance participation. Feedback from the review suggests improving error handling for missing API keys by removing the ?? "" fallback, and externalizing hardcoded thresholds and alert levels from the system prompt strings in both new agents for better maintainability.
| ANTHROPIC_API_KEY: process.env.ANTHROPIC_API_KEY ?? "", | ||
| LEDGER_MCP_API_KEY: process.env.LEDGER_MCP_API_KEY ?? "", | ||
| KOI_MCP_API_KEY: process.env.KOI_MCP_API_KEY ?? "", |
There was a problem hiding this comment.
Using ?? "" for API keys can lead to runtime errors if the environment variables are not set and the API clients do not gracefully handle empty keys. It's generally safer to explicitly check for the presence of mandatory environment variables and throw an error if they are missing, rather than providing an empty string fallback that might cause silent failures or cryptic errors later in the API call.
| ANTHROPIC_API_KEY: process.env.ANTHROPIC_API_KEY ?? "", | |
| LEDGER_MCP_API_KEY: process.env.LEDGER_MCP_API_KEY ?? "", | |
| KOI_MCP_API_KEY: process.env.KOI_MCP_API_KEY ?? "", | |
| ANTHROPIC_API_KEY: process.env.ANTHROPIC_API_KEY, | |
| LEDGER_MCP_API_KEY: process.env.LEDGER_MCP_API_KEY, | |
| KOI_MCP_API_KEY: process.env.KOI_MCP_API_KEY, |
| ANTHROPIC_API_KEY: process.env.ANTHROPIC_API_KEY ?? "", | ||
| LEDGER_MCP_API_KEY: process.env.LEDGER_MCP_API_KEY ?? "", | ||
| KOI_MCP_API_KEY: process.env.KOI_MCP_API_KEY ?? "", |
There was a problem hiding this comment.
Using ?? "" for API keys can lead to runtime errors if the environment variables are not set and the API clients do not gracefully handle empty keys. It's generally safer to explicitly check for the presence of mandatory environment variables and throw an error if they are missing, rather than providing an empty string fallback that might cause silent failures or cryptic errors later in the API call.
| ANTHROPIC_API_KEY: process.env.ANTHROPIC_API_KEY ?? "", | |
| LEDGER_MCP_API_KEY: process.env.LEDGER_MCP_API_KEY ?? "", | |
| KOI_MCP_API_KEY: process.env.KOI_MCP_API_KEY ?? "", | |
| ANTHROPIC_API_KEY: process.env.ANTHROPIC_API_KEY, | |
| LEDGER_MCP_API_KEY: process.env.LEDGER_MCP_API_KEY, | |
| KOI_MCP_API_KEY: process.env.KOI_MCP_API_KEY, |
| - WF-MM-01 (Price Impact Alert): Detect price anomalies using z-score analysis (threshold: 2.5). Score against batch, class, and external medians. | ||
| - WF-MM-02 (Liquidity Monitor): Hourly liquidity health checks. Track listed value, bid-ask spreads, and order book depth. | ||
| - WF-MM-03 (Retirement Tracking): Analyze retirement events for demand signals, impact quantification, and trend extraction. | ||
|
|
||
| Alert Severity Levels: | ||
| - INFO: Normal market activity, logged for trend analysis | ||
| - WARNING: Anomaly z-score 2.0-3.5, added to watchlist | ||
| - CRITICAL: Anomaly z-score >= 3.5, escalate for investigation |
There was a problem hiding this comment.
The z-score thresholds and alert severity levels are hardcoded directly within the system prompt string. For better maintainability and easier programmatic access or updates, consider defining these thresholds (e.g., 2.5, 2.0-3.5, >= 3.5) as constants outside the string and injecting them. This makes it easier to manage these critical values if they need to be adjusted or referenced elsewhere in the codebase.
| Alert Levels: | ||
| - NORMAL: Metrics within healthy bounds | ||
| - WARNING: Degradation detected (e.g., uptime drop, concentration increase) | ||
| - CRITICAL: Immediate risk to network health (e.g., validator down, >33% concentration) |
There was a problem hiding this comment.
The alert levels and their conditions are hardcoded directly within the system prompt string. For better maintainability and easier programmatic access or updates, consider defining these thresholds (e.g., >33% concentration) as constants outside the string and injecting them. This makes it easier to manage these critical values if they need to be adjusted or referenced elsewhere in the codebase.
…tations
- Replace hardcoded dates (2026-03-25T14:32:00Z etc.) with [TIMESTAMP]
placeholders and relative periods ("Past 7 days") in message examples
- Fix WF-VM-03 label: "Governance Participation Monitor" →
"Network Decentralization Monitoring" (matching phase-2/2.2 spec)
- Add JSDoc citations to exact spec sections in phase-2/2.2 for all
workflow IDs (WF-MM-01/02/03/04, WF-VM-01/02/03)
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
…constants Address gemini-code-assist review feedback on PR regen-network#64: 1. Replace `process.env.X ?? ""` with `requireEnv("X")` in both market-monitor and validator-monitor character definitions. Missing API keys now throw immediately at startup instead of silently passing empty strings that cause cryptic failures downstream. 2. Extract hardcoded thresholds (z-score levels, confidence ranges, scoring weights, concentration limits) from system prompt strings into named THRESHOLDS constants. The system prompt interpolates these values, keeping a single source of truth that downstream tooling can also reference programmatically. 3. Export `requireEnv` from @regen/core so character definitions can reuse the existing validation helper. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Mirrors the AGENT-002 Governance Analyst structure to give AGENT-003 Market Monitor the same full standalone TypeScript implementation that AGENT-002 has: - `agent-003-market-monitor/` — standalone Node.js process - `src/index.ts` — banner, cycle runner, polling vs single-run mode - `src/config.ts` — config + thresholds mirrored from the character - `src/types.ts` — ecocredit marketplace types + per-workflow shapes - `src/ledger.ts` — LCD client for ecocredit + marketplace endpoints - `src/store.ts` — SQLite state (trade obs, anomaly dedupe, liquidity snapshots, retirement summaries, workflow executions) - `src/ooda.ts` — generic OODA executor (same shape as agent-002) - `src/monitor.ts` — Claude narrative layer, one function per workflow - `src/output.ts` — console + optional Discord webhook dispatcher - `src/workflows/price-anomaly-detection.ts` — WF-MM-01 - `src/workflows/liquidity-monitor.ts` — WF-MM-02 - `src/workflows/retirement-tracking.ts` — WF-MM-03 Design decisions documented in the agent README: 1. Deterministic numbers, narrative-only LLM calls. All severity classification, z-score computation, liquidity health scoring, and demand index derivation happen locally. Claude only writes the report from those numbers. Keeps the agent cheap, reproducible, and auditable. 2. Sell-order-as-trade proxy for the MVP until Ledger MCP exposes filled-trade events. The code path swaps cleanly once real trade events are available. 3. Batch-supply delta as the retirement source for the MVP, capped at 100 most recent batches per cycle to protect the LCD. A follow-up PR will plug in a real MsgRetire tx-stream client. 4. Alert dedupe by (trade_id, severity) — a trade that escalates from WARNING to CRITICAL still fires a new alert; a same-severity re-alert does not. Thresholds (`config.market.*`) mirror the character definition at `agents/packages/agents/src/characters/market-monitor.ts` so downstream tooling has a single source of truth. Anomaly severity boundaries (WARNING >= 2.0, CRITICAL >= 3.5 z-score) and the liquidity depth floor live in `config.ts` and are referenced from the system prompt. CI: the new agent is added to the `agents` job so `npx tsc --noEmit` runs against it on every PR, matching how agent-002-governance-analyst is wired. - Lands in: `agent-003-market-monitor/`, `.github/workflows/ci.yml` - Changes: new standalone AGENT-003 process with 3 workflows (WF-MM-01/02/03) - Validate: `cd agent-003-market-monitor && npm ci && npx tsc --noEmit` Refs phase-2/2.2-agentic-workflows.md §WF-MM-01, §WF-MM-02, §WF-MM-03 Refs agents/packages/agents/src/characters/market-monitor.ts (regen-network#64)
Mirrors the AGENT-002 / AGENT-003 structure to give AGENT-004 Validator Monitor the same standalone TypeScript implementation: - `agent-004-validator-monitor/` — standalone Node.js process - `src/index.ts` — banner, cycle runner, polling vs single-run mode - `src/config.ts` — config + thresholds mirrored from the character - `src/types.ts` — staking / slashing / gov types + per-workflow shapes - `src/ledger.ts` — LCD client for staking, slashing, gov endpoints - `src/store.ts` — SQLite state (token snapshots, commission history, scorecards, decentralization snapshots, workflow executions) - `src/ooda.ts` — generic OODA executor (same shape as agent-002/003) - `src/monitor.ts` — Claude narrative layer, one function per workflow - `src/output.ts` — console + optional Discord webhook dispatcher - `src/workflows/performance-tracking.ts` — WF-VM-01 - `src/workflows/delegation-flow-analysis.ts` — WF-VM-02 - `src/workflows/decentralization-monitor.ts` — WF-VM-03 Scoring (M014): - Uptime component: signed_blocks_window − missed_blocks_counter, weighted at config.validator.scoreWeightUptime (default 400) - Governance component: votes cast / recent finalized proposals, weighted at config.validator.scoreWeightGovernance (default 350) - Stability component: full weight minus penalties for jailing (100) and commission changes in the trailing window (40 each), floored at 0, weighted at config.validator.scoreWeightStability (default 250) - Composite = sum, 0..1000, PoA eligible when >= 800 Decentralization (WF-VM-03): - Nakamoto coefficient uses the 33.4% halt-threshold convention - Gini index uses the textbook formula on token amounts normalized to uregen - Health classification from Nakamoto floor (<=5 CRITICAL, <=8 WARNING), Gini ceiling (>=0.65 WARNING), and single-validator concentration (>=33% CRITICAL, >=20% WARNING) Delegation flows (WF-VM-02): - Snapshot each validator's `tokens` field every cycle - Derive flows from the delta against the previous snapshot - Whale-sized movements (>= 100,000 REGEN by default) tagged in the summary and raise the alert level Determinism: all scoring, Nakamoto, Gini, health, and whale detection are computed in plain TypeScript. Claude is only used for the narrative layer. Keeps the agent cheap, reproducible, and auditable — and makes the hard parts trivially unit-testable in a follow-up PR. Deliberate MVP proxies (documented in the agent README): 1. Token-delta as the delegation source for WF-VM-02 until a real MsgDelegate / MsgUndelegate / MsgRedelegate tx-stream client lands. 2. Governance participation currently scores 0 for every validator because the operator→delegator bech32 conversion is deferred to a follow-up PR. Relative composites still surface real differences in uptime and stability without asymmetric penalty. 3. MVP signing-info join on the raw consensus key — falls back to assuming 100% uptime when no match is found, which under-counts real issues rather than smearing a healthy validator. CI: the new agent is added to the `agents` job so `npx tsc --noEmit` runs against it on every PR, matching the existing agent-002-governance-analyst wiring. - Lands in: `agent-004-validator-monitor/`, `.github/workflows/ci.yml` - Changes: new standalone AGENT-004 process with 3 workflows (WF-VM-01/02/03) - Validate: `cd agent-004-validator-monitor && npm ci && npx tsc --noEmit` Refs phase-2/2.2-agentic-workflows.md §WF-VM-01, §WF-VM-02, §WF-VM-03 Refs agents/packages/agents/src/characters/validator-monitor.ts (regen-network#64)
The AGENT-001 Registry Reviewer standalone TypeScript implementation has been in the repo since PR regen-network#64 but was never wired into the CI `Agents` job. Only `agents/` (the ElizaOS character pack) and `agent-002-governance-analyst/` run `npx tsc --noEmit` on every PR. `agent-001-registry-reviewer/` has its own `package.json`, `tsconfig.json`, and a full workflow implementation (reviewer, ooda, 3 workflows, ledger client, store, types). It compiles cleanly on Node 22 locally — this PR adds it to the CI matrix so regressions are caught on every PR. After PRs regen-network#80 and regen-network#81 (which added agent-003 and agent-004 to CI), this PR closes the gap for the only remaining unwired standalone agent: agent-001. The full CI Agents job now typechecks four standalone agent processes: agents/ (ElizaOS character pack) agent-001-registry-reviewer/ (this PR) agent-002-governance-analyst/ (already wired) agent-003-market-monitor/ (added in PR regen-network#80) agent-004-validator-monitor/ (added in PR regen-network#81) ## Validation $ cd agent-001-registry-reviewer && npm ci && npx tsc --noEmit (exit 0) Same commands as the CI step. - Lands in: `.github/workflows/ci.yml` - Changes: add agent-001-registry-reviewer npm ci + typecheck steps - Validate: `cd agent-001-registry-reviewer && npm ci && npx tsc --noEmit`
2 participants
Summary
market-monitor.ts): Layer 1 fully automated agent for credit price monitoring, marketplace liquidity tracking, retirement pattern analysis, fee revenue reporting, and anomaly detection (WF-MM-01 through WF-MM-03)validator-monitor.ts): Layer 1 fully automated agent for validator performance scoring (M014), delegation flow analysis, governance participation tracking, and PoA transition readiness assessment (WF-VM-01 through WF-VM-03)agents/packages/agents/src/index.tsCHARACTERS mapstart:marketandstart:validatorscripts toagents/package.jsonCompletes the four-agent roster specified in phase-2/2.4-agent-orchestration.md. Both characters follow the same ElizaOS v1.6.3 Character interface pattern established by AGENT-001 (Registry Reviewer) and AGENT-002 (Governance Analyst).
Test plan
npm run lintin agents/)AGENT_CHARACTER=market-monitorselects the correct character at runtimeAGENT_CHARACTER=validator-monitorselects the correct character at runtime🤖 Generated with Claude Code